RFC: Galacean Entity/Component 克隆行为统一方案

• 关联 PR: galacean/engine#2992 fix(clone): preserve target instance + Map/Set deep clone + cycle detection
• 作者: 阿霑 + Claude (migration-agent 视角)
• 日期: 2026-05-19
• 状态: Draft（讨论中，未实施）
• 目标读者: 引擎核心 (luzhuang 等)、migration-agent 维护者、业务接入方

0. TL;DR

PR #2992 解决了 4 类 prefab clone 引用泄漏（target-instance preservation / Map+Set / cycle / Assignment 不升级），但是这只是冰山一角。这次 Cocos → Galacean 转换 18 个项目里，克隆相关 bug 数量是单类 bug 之最，其中相当一部分不是 cloneProperty 内部的修复能覆盖到的，分散在 _setTransformEntity listener 注册、CloneUtils._getEntityHierarchyPath 空 parent 容错、@assignmentClone vs 引擎共享对象（AnimatorState）的语义错配、以及 CloneMode.Shallow 实际上从来没被任何调用方使用过等多处。

这份 RFC 的目标是：

1. 把所有已遇到的克隆相关问题集中陈列，让 PR fix(clone): preserve target instance + Map/Set deep clone + cycle detection #2992 的范围决策可被验证；
2. 提出一个统一的 clone 语义模型（"按引用域划分"），让后续每一个 @xxxClone 装饰器的使用都有规范；
3. 指出 PR fix(clone): preserve target instance + Map/Set deep clone + cycle detection #2992 之外仍需处理的边界，作为后续 follow-up issue 的源头。

1. 背景：为什么 clone 在迁移项目里被反复踩

Cocos Creator 的 cc.instantiate(prefab) 和 Galacean 的 entity.clone() / prefabResource.instantiate() 表面 1:1，但底层规则差异巨大：

业务层一旦从 Cocos 心智模型出发写脚本，遇到旧版 Galacean 默认行为，几乎所有"运行时初始化的私有缓存对象"都会在第二个 prefab 实例里串数据。这是这次 18 个项目转换中"主角衣服换不掉 / SMR culling 异常 / Animator 串速 / UI 多次点击叠加" 等表象问题的共同根因。

cloneEngine fork 在 PR #2992 之前已经分阶段做了 5 个 commit 的修复（见 PR 描述）；本 RFC 用来固化这些修复并补齐边界。

2. 当前 PR #2992 解决的问题

按代码顺序逐条对照：

2.1 同类型 target 实例保留

// 4. Determine effective clone mode
let effectiveCloneMode: CloneMode = cloneMode;
if (effectiveCloneMode === undefined) {
  effectiveCloneMode = CloneManager._inferCloneMode(sourceProperty, target[k]);
} else if (effectiveCloneMode !== CloneMode.Assignment) {
  // Decorated Shallow/Deep: upgrade to Deep if target already has independent same-type instance.
  if (
    targetProperty &&
    targetProperty !== sourceProperty &&
    targetProperty.constructor === sourceProperty.constructor
  ) {
    effectiveCloneMode = CloneMode.Deep;
  }
}

解决的问题：脚本/组件 constructor 里 new Vector3() / new Color() 这种字段，在旧版被 source 的引用直接覆写，导致两个实例共享一个内部 buffer。修复后保留 target 自己的实例并 copyFrom。

2.2 Map / Set 深克隆 + 元素 remap

case Map: /* ... clear + forEach + _remap key/value ... */
case Set: /* ... clear + forEach + _remap value ... */

解决的问题：业务用 Map<string, Entity> / Set<Component> 缓存引用时，旧版直接共享引用，clone 出来的实例和模板共享同一 Map。

2.3 循环 / 共享引用检测前置

// Check if we've already visited this source object (cycle detection)
if (deepInstanceMap.has(sourceProperty)) {
  target[k] = deepInstanceMap.get(sourceProperty);
  return;
}

解决的问题：旧版只在 targetProperty 为空时查 deepInstanceMap，已有 target 时直接 fall-through，结果是同一 source 对象在 clone tree 内两个位置被复制成两个不同的 target。修复后无条件先查 map。

2.4 CloneMode.Assignment 永不升级

} else if (effectiveCloneMode !== CloneMode.Assignment) { /* upgrade ... */ }

解决的问题：用户显式 @assignmentClone 标记的字段，意图就是 "clone 后共享引用"（典型场景：单例 manager 引用、引擎资源引用），如果被自动升级成 Deep 反而破坏意图。

2.5 推断规则中的兜底

private static _inferCloneMode(sourceProperty: Object, targetProperty: any): CloneMode {
  // ... 类型推断 ...
  // Other class instances (engine resources like Material, Texture) - shared reference
  return CloneMode.Assignment;
}

解决的问题：Material / Texture / Mesh 等引擎资源，在 cocos 心智里也是共享的，PR 把"未识别的 class 实例"降到 Assignment 而不是 Deep，避免错把资源克隆出几份。

2.6 ModelMesh throw string → throw Error

附带改动，让 stack trace 可读。和 clone 本身无关。

3. PR #2992 之外，迁移项目中遇到但未解决的克隆问题

以下每条都来自 18 个项目里实际踩过的 case，附 commit hash / 文件路径作证。

3.1 _remap 优先级高于 @ignoreClone，绕过 _setTransformEntity listener 注册

症状：SkinnedMeshRenderer.bounds 冻结在初始位置，clone 出来的角色 frustum culling 错误地隐藏掉。

根因：

• Renderer._transformEntity 字段在引擎层既是缓存又承担 listener owner 角色（add listener on _updateFlagManager）。
• Entity._remap 走 CloneManager.cloneProperty 的第 1 步（最高优先级），直接 target._transformEntity = remappedEntity，不会经过 _setTransformEntity() setter。
• 紧接着 _cloneTo → _applySkin → _setTransformEntity(rootBone) 时，setter 里的相等守卫 if (entity !== preEntity) 命中（两边都是 remapped rootBone）→ 跳过 add listener。
• 最终：clone 出来的 SMR 的 _onTransformChanged 监听器从未注册到 rootBone 的 _updateFlagManager，rootBone 移动时 SMR.bounds 不会失效，culling 永远用初始 bounds。

migration-agent 当前 workaround（compat-runtime.ts，所有 18 个项目都装了）：

function installSetTransformEntityPolyfill(): void {
  // 去掉相等守卫，每次都先 remove 再 add，零额外运行时开销
  rendererProto._setTransformEntity = function (entity) {
    const pre = this._transformEntity;
    if (pre) pre._updateFlagManager.removeListener(this._onTransformChanged);
    if (entity) entity._updateFlagManager.addListener(this._onTransformChanged);
    this._transformEntity = entity;
  };
}

根治建议：见 §5.1。这本质上是引擎对"哪些字段必须经过 setter"缺少强制约束，需要在 clone 阶段对此类字段提供 hook。

Commit ref：ef35d1768 fix(compat): patch _setTransformEntity to fix SMR bounds frozen after clone

3.2 CloneUtils._getEntityHierarchyPath 对已 destroy entity 不容错

症状：clone prefab 时抛 TypeError: Cannot read properties of undefined (reading 'parent')。

根因：

private static _getEntityHierarchyPath(rootEntity, searchEntity, inversePath): boolean {
  inversePath.length = 0;
  while (searchEntity !== rootEntity) {
    const parent = searchEntity.parent;
    if (!parent) return false;  // 这一步对 entity._dispose 后 parent=undefined 是 OK 的
    inversePath.push(searchEntity.siblingIndex);
    searchEntity = parent;
  }
  return true;
}

但当 searchEntity 本身是 undefined（业务 listener 持有 destroyed entity，引擎 nullify 了 .entity 字段）时，第一行 searchEntity.parent 就抛 NPE。

PR #2992 没有处理这一路径。

migration-agent 当前 workaround：在 converter 层把 _LISTENER_HOLDER_FIELDS 显式列出（如 clickEvents / pageEvents / scrollEvents 等），对应字段在序列化期就剔除掉 destroyed entity 引用。

Commit ref：eeab33b01 fix(converters): _LISTENER_HOLDER_FIELDS 补 pageEvents / scrollEvents

根治建议：见 §5.2。

3.3 EventHandler[] 数据数组事件 clone 后累加

症状：HanBao upgradeInfo.lv 点击一次升 16 级；clone 出的 UI 节点点击事件被触发 N 次。

根因：cocos 的 Button.clickEvents: ComponentEventHandler[] 是数据数组（plain object 数组，每项 { target, _componentName, _handler, customEventData }）。Galacean 把它翻译为 Signal / NodeEvent.on(...) 时，clone 之后业务代码会做 events.push(eh) 累加，结果一个按钮挂了多份 listener。

PR #2992 让 plain object 自动深克隆 + remap entity 引用，但数组事件的"清空 + 重建"语义不是 CloneManager 能感知的——这需要业务层（或 compat 层）按 cocos 语义重写。

migration-agent 当前 workaround（feedback_cocos_data_array_event_compat.md）：compat 层 patch Button.prototype.clickEvents getter/setter，业务保持 cocos 写法 length=0; push(eh) 直翻。

这不是 CloneManager 能修的，但 RFC 需要把它列出来，说明"clone 自动深拷贝"对数据数组事件模型仍然不够，业务需要识别这一模式。

Commit ref：feedback_cocos_data_array_event_compat.md

3.4 共享 AnimatorController.layers[].stateMachine.states（不是 clone bug，是设计 bug）

症状：prefab A 的 Animator setState speed = 2，prefab B 的同 controller 也变 2。

根因：Galacean AnimatorController 是一个 engine 资源，多 prefab 实例共享。state.speed 不在 per-instance Animator 上，而在 shared AnimatorState 对象上。clone Animator 时 controller 走 Assignment（资源共享是对的），但有些状态本来就该 per-instance，引擎 API 不分。

migration-agent 当前 workaround：compat AnimatorStateCompat 在 per-Animator pending state speed map 里维护，setter 不写共享对象。

这不是 CloneManager 的责任，但是和 clone 语义紧密相关："哪些是资源（assignment）、哪些是 per-instance state"在 cocos 心智模型里是 component 字段 vs AnimationClip 资源的清晰区分；Galacean 把 state 折到 controller 里就模糊了这条线。

Commit ref：galacean_migration_outputs/*/converters/assets/compat/animation/animator-compat.ts:53-72

3.5 CloneMode.Shallow 几乎是死代码

现状：枚举里有 Ignore / Assignment / Shallow / Deep 四个；cloneProperty 内部把 Shallow 当 Deep 处理（switch 分支不区分）；类型推断 _inferCloneMode 也不会返回 Shallow。

问题：Shallow 是"创建新容器、但元素走 Assignment"的语义，理论上对业务自定义类的数组成员有用（每个 entity 独立 array，但 element ref 跨树共享）。当前实现没体现这点，反而是 Deep 在用 cloneMode 透传到 array element 时模糊地兼用了。

PR #2992 的 _inferCloneMode 里只用 Deep / Assignment 两个值返回。

建议：要么明确 Shallow 的精确语义（"array 元素 1 级浅复制，不进 sub-cloneProperty"），要么 deprecate 并文档化等价于 Deep。当前模糊状态会让用户写 @shallowClone 时无法预测行为。

3.6 copyFrom 调用没有 fall-back 守卫

现状：

if ((<ICustomClone>sourceProperty).copyFrom) {
  (<ICustomClone>targetPropertyD).copyFrom(<ICustomClone>sourceProperty);
}

问题：如果 target 不是 source 的同类（比如 source 是 Vector3、target 是用户的 MyVec 仅恰好有同名 copyFrom 方法），会调到错的实现。

PR #2992 的 §2.1 引入了 targetProperty.constructor === sourceProperty.constructor 检查，但只在"装饰过/未装饰路径"上判，default branch 内部走 copyFrom 时不再验类型——因为前面已经走过 inferCloneMode 推断了 deep。但如果用户用 @deepClone 装饰一个字段，target 里又被另一个 constructor 提前赋了一个"有同名 copyFrom 但语义不同"的对象，这个 case 仍然走 copyFrom 而不报错。

建议：default branch 内部加 constructor 校验，不匹配时退回到 "new + per-key" 路径。

3.7 Component._remap 用 _components.indexOf 在多实例场景脆弱

static remapComponent<T extends Component>(srcRoot, targetRoot, component: T): T {
  // ...
  return CloneUtils._getEntityByHierarchyPath(targetRoot, path)
    ._components[srcEntity._components.indexOf(component)] as T;
}

问题：同 entity 上挂两个相同类的 Component（cocos 允许），引用某个具体实例时 indexOf 依赖插入顺序——但 cloneEngine 当前 _createCloneEntity 用 componentConstructors 数组 new，理论上顺序一致，可一旦组件被 sort/swap 过（例如 UI sortIndex 重排），就会 remap 到错的兄弟组件。

建议：增加 _componentInstanceIndex（per-entity per-type 的 index）作为更稳的 ID。或者在 _createCloneEntity 阶段冻结顺序约定并文档化。

PR #2992 没碰这一块。

3.8 GLB 内部子节点跨 clone 边界的 entityPath（converter 侧问题，非引擎 clone）

为什么提：用户视角 "clone 出问题" 经常包含 prefab 实例化 GLB 后子节点引用错位，但这一类不是 CloneManager 的问题，是 scene/prefab 序列化层的 entityPath 解析问题。RFC 划清界限：

• CloneManager 责任：runtime entity.clone() 时 entity tree 内 ref remap。
• scene-prefab converter 责任：把 cocos cc.PrefabInstance.propertyOverrides 翻成 Galacean modifications，并保证跨 nested-prefab / FBX-wrapper / GLB-collapsed 的 entityPath 正确。

历史上 D.2~D.5 一系列 commit（9998a8975 / b056edd78 / cfe36b2d0 / d48d70016 等共 ~15 个）都在 converter 侧解决，不影响 PR #2992。

RFC 建议：在 CloneManager 文档里加一句"clone 不负责 GLB 内部 entity 的层级解析，那是资产加载器的事"，避免后续接入方混淆。

4. 设计原则

收敛上述问题，我提出 4 条原则作为后续 clone 行为的判断依据：

P1. 引用域优先于装饰器

字段的 clone 行为应该由**该引用指向的"对象的所属域"**决定，而不是用户记不记得加 @xxxClone：

PR #2992 的 _inferCloneMode 实质上已经在按这个方向走，但还缺**"外部句柄"的自动识别**——目前都靠用户写 @ignoreClone。这条线建议保持显式（自动识别 DOM 类型容易误伤），但文档要明确"外部句柄必须 @ignoreClone"。

P2. setter 副作用必须显式走 hook，不能依赖 setter 守卫

Renderer._setTransformEntity、UICanvas._setComponentMask 等"setter 里有重要副作用（add/remove listener）"的字段，不能假设 clone 走的是赋值路径。当前 _remap 直接覆写 _transformEntity 就绕过了 setter；如果未来还有别的字段也是这种结构，会再次踩同样的坑。

根治方案：

• 选项 A：clone 阶段对装饰为 @remapClone（新装饰器）的字段，走 _setXxxFromClone 钩子（默认就是 setter）。
• 选项 B：clone 流程结束后，对所有 Renderer 强制调一次 _setTransformEntity(_transformEntity) 重置 listener。
• 选项 C：把 listener owner 从 _transformEntity 分离出来到独立字段，避免和 cache 字段耦合。

我倾向选项 B（最小侵入，对所有 Renderer 派生类生效）。RFC 应该选定一个并写进引擎。

P3. Map/Set/Array 元素 remap 已对齐 — 但对象 key 的 remap 仍有边界

PR #2992 对 Map.key 也走 _remap，但 cocos 里几乎不会用 Entity 当 key（用作 value 居多）；如果 key 是 plain object，旧逻辑就直接共享 key 引用（PR 没有把 Map.key 走 deep）。

建议：明确文档"Map key 不做 deep clone，永远是 reference + 可选 remap"；测试用例补一条 "key 是 plain object 的 Map clone 后 key 仍共享" 来锁定行为。

P4. 类型推断的兜底必须保守

_inferCloneMode 最后一条 return CloneMode.Assignment（未识别的 class 实例）是一个保守兜底。但如果未来有用户写了自定义 class Foo { x = new Vector3() } 并赋给字段，因为 Foo 没有 copyFrom、constructor !== Object，会走 Assignment——结果 clone 出来 Foo 实例被共享，内部 Vector3 也被共享。

建议：要么文档化 "自定义 class 字段默认共享，需要独立请加 @deepClone"，要么把推断改为"自定义 class（非引擎资源 / 非外部句柄）默认 Deep"。后者更安全但有兼容风险。

PR #2992 选了前者（兜底 Assignment）。我认可这个选择，但需要在 IClone 文档里高亮"自定义 class 默认共享"。

5. 具体待落地动作

按优先级：

5.1 [P0] 修复 _setTransformEntity listener 注册（§3.1）

Renderer._setTransformEntity 去掉相等守卫 — 这正是 migration-agent compat 层做的事，引擎合并后 18 个项目可以删 polyfill。

 protected _setTransformEntity(entity: Entity): void {
   const preEntity = this._transformEntity;
-  if (entity !== preEntity) {
-    preEntity?._updateFlagManager.removeListener(this._onTransformChanged);
-    entity?._updateFlagManager.addListener(this._onTransformChanged);
-    this._transformEntity = entity;
-  }
+  preEntity?._updateFlagManager.removeListener(this._onTransformChanged);
+  entity?._updateFlagManager.addListener(this._onTransformChanged);
+  this._transformEntity = entity;
 }

调用方影响：所有非 clone 路径调用 _setTransformEntity(samEntity)（罕见）会多一次 remove+add，开销 < 1μs，可忽略。

或 在 clone 完成后强制刷一次（选项 B）：

// CloneManager / Entity._clone 末尾
target.getComponentsIncludeChildren(Renderer, tempArr);
for (const r of tempArr) r._setTransformEntity(r._transformEntity);

侵入更小但需要遍历组件树。我倾向第一种。

5.2 [P0] CloneUtils._getEntityHierarchyPath 对 undefined 容错（§3.2）

 private static _getEntityHierarchyPath(rootEntity, searchEntity, inversePath): boolean {
   inversePath.length = 0;
+  if (!searchEntity) return false;  // destroyed entity ref
   while (searchEntity !== rootEntity) {
     const parent = searchEntity.parent;
     if (!parent) return false;
     inversePath.push(searchEntity.siblingIndex);
     searchEntity = parent;
   }
   return true;
 }

外面调用方拿到 false 后 fall-back 到"返回原 component / 原 entity"（即外部引用语义），不会塞 undefined 进 clone target。

5.3 [P1] _inferCloneMode 加 PR #2992 自身仍欠的 cycle 前置检查日志

PR 在 default branch 加了 deepInstanceMap.has(sourceProperty) → 返回缓存。但装饰过 @deepClone 的同一字段，如果两个 entity 引用同一 source，也会走到这里——目前是直接返回缓存（正确）；但如果用户的本意是"每个引用各自一个独立 clone"（罕见），当前 API 无法表达。

建议：文档化 "deepClone 装饰的字段，跨字段共享同一 source 引用时，clone 后也共享"（即 cycle dedup 行为是默认且无法关闭）。这是 PR #2992 的设计选择，明文写进 JSDoc。

5.4 [P1] 明确 / Deprecate CloneMode.Shallow（§3.5）

PR #2992 没动 Shallow。两个方案选一：

• A：实现 Shallow 的真实语义（array 元素直接 Assignment，不深递归），写测试。
• B：标记 CloneMode.Shallow deprecated，提示 "use Deep + 装饰元素类型" 替代；在引擎里走和 Deep 一致的处理。

我倾向 B（Shallow 当前没有用户）。

5.5 [P1] 文档化"自定义 class 字段默认 Assignment"（§4 P4）

在 @galacean/engine 文档站的 Clone 章节加一节"自定义类型字段"，明确推断规则，给出最佳实践：

class MyScript extends Script {
  @deepClone  // 强制独立
  private _state = new MyState();

  private _runtimeOnly = new DomHandler();  // 默认 Assignment，OK

  @ignoreClone
  private _domEl: HTMLElement = null;  // 外部句柄
}

5.6 [P2] Component._remap 加多组件场景测试（§3.7）

补一个测试：同 entity 挂两个 Behavior 实例，prefab clone 后引用各自的 instance，验证 _components.indexOf 在简单情况下能区分。如果失败，加 _componentInstanceIndex。

5.7 [P2] 测试覆盖补充

PR #2992 当前测试已覆盖：

• ✅ Undecorated entity array
• ✅ Undecorated object with entity ref
• ✅ Nested array of arrays
• ✅ Map with entity values
• ✅ Plain object now deep cloned (was assignment)

缺：

• ❌ Constructor-created Vector3 field 不被 source 覆写（这是 PR §2.1 的核心 case，目前测试里没单独验证）
• ❌ Cycle reference graph（描述里提了，测试里没）
• ❌ @assignmentClone 显式标记字段 + target 已有同类型实例 → 仍然 Assignment（PR §2.4 的核心 case）
• ❌ Set with entity values（Map 测了，Set 没）
• ❌ SMR clone 后 bounds 跟随 rootBone 移动（§3.1 的端到端验证）
• ❌ Listener target.entity = undefined 不抛 NPE（§3.2）

5.8 [P3] 文档"clone vs scene/prefab 序列化"边界（§3.8）

在 CloneManager JSDoc 顶部加："CloneManager handles runtime entity.clone() only. Cross-asset references (GLB sub-entity refs, nested PrefabResource overrides) are resolved at asset load / scene deserialization, see PrefabResource / SceneLoader."

6. 行为对照表（最终态）

按字段类型 × 装饰器组合的预期行为：

⚠️ 行：是当前默认行为可能不符合用户预期的格子，需要文档明确。

7. 破坏性变更评估

PR #2992 已经引入了一处破坏：

clonedScript.data 在未装饰时从"共享引用"变成"独立 deep clone"

测试 CloneUtils.test.ts:264-269 显示了行为变化：

- expect(clonedScript.data).eq(obj);
+ expect(clonedScript.data).not.eq(obj);
+ expect((<any>clonedScript.data).x).eq(1);

影响范围：所有 cocos→galacean 业务代码里"私有缓存对象"在旧版会共享，clone 后两个实例改 cache 会互相影响——这恰恰是 cocos 业务的 bug。修复后正确。

风险：原生 galacean 用户如果有意在 clone 后共享 plain object，会受影响。需在 release note 标注，建议加 @assignmentClone 显式保留旧行为。

§5 提议的其他改动（5.1 setter listener、5.2 NPE 容错）都是 bug fix，无 API 破坏。

8. 不在本 RFC 范围

为避免 scope creep，以下问题虽然和 clone 沾边，不在本 RFC 处理：

1. converter 侧 GLB collapse / nested prefab override（§3.8）— migration-agent 仓库内问题，不涉及引擎。
2. AnimatorState per-instance speed（§3.4）— 这是 AnimatorController 设计问题，需要单独 RFC。
3. EventHandler[] 数据数组事件模型（§3.3）— 业务/compat 层处理，引擎不感知。
4. 业务脚本翻译 .clone() 滥用（fact-card 已修，migration-agent 内问题）。
5. Material getMaterial() vs getInstanceMaterial() 的 clone-on-write 语义 — 已对齐，但属于 Renderer API 设计。

9. 决策待定项

需要 luzhuang / 引擎 owner 拍板的：

1. §5.1 _setTransformEntity 修复路径：去守卫 vs clone 后强制刷新 vs 拆字段，选哪个？
2. §5.4 CloneMode.Shallow：实装真实语义 vs deprecate？
3. §4 P4 自定义 class 推断：保守 Assignment 兜底 vs 默认 Deep？
4. §5.3 deepInstanceMap dedup 是否需要可配置的 "per-field 独立 clone" 开关？

10. 落地路线图（如果方案通过）

1. Phase 1（PR fix(clone): preserve target instance + Map/Set deep clone + cycle detection #2992 当前范围）：合并 cloneProperty 重构 + Map/Set + cycle + Assignment 不升级 + ModelMesh Error。
2. Phase 2（本 RFC §5.1 + §5.2）：_setTransformEntity 修复 + _getEntityHierarchyPath NPE 容错，单独 PR。
3. Phase 3（§5.4 + §5.5 文档）：行为对照表入文档站，CloneMode.Shallow 决策。
4. Phase 4（§5.6 + §5.7 测试）：补全测试矩阵。
5. Phase 5：migration-agent compat 层删 installSetTransformEntityPolyfill，验证 18 个项目无 regression。

附录 A：migration-agent 项目里 clone 相关问题完整索引

引用源 commit hash 见 git log；下表只列代表性 case：

附录 B：测试用例完整建议清单

// 1. Constructor-created field preservation
class S1 extends Script { v = new Vector3(1, 2, 3); }
// clone 后 cloned.v !== src.v，但 cloned.v.x===1

// 2. Cycle detection
class S2 extends Script { ref: S2 = null; }
s2.ref = s2;
// clone 不死循环，cloned.ref === cloned

// 3. Shared sub-graph
class S3 extends Script { a: Foo; b: Foo; }
s3.a = s3.b = sharedFoo;
// clone 后 cloned.a === cloned.b (dedup), 但 !== sharedFoo

// 4. @assignmentClone never upgrade
class S4 extends Script { @assignmentClone v = new Vector3(); }
// clone 后 cloned.v === src.v (引用共享)

// 5. Set with entity values
class S5 extends Script { entities = new Set<Entity>(); }
// clone 后 entities 是新 Set，internal entity 被 remap

// 6. Custom class default Assignment
class Foo {}
class S6 extends Script { foo = new Foo(); }
// clone 后 cloned.foo === src.foo

// 7. SMR bounds tracks rootBone after clone (§3.1)
// clone SMR → move rootBone → bounds.update()

// 8. Listener target.entity = undefined doesn't NPE (§3.2)
// listener.target = { entity: undefined } → clone 不抛错

// 9. Plain object key in Map is shared not deep
const k = { id: 1 };
class S9 extends Script { m = new Map([[k, 'v']]); }
// clone 后 cloned.m.keys() 仍含 k 引用 (§4 P3)

讨论：评论于 galacean/engine#2992 或单独开 issue 关联本 RFC。